B.3.2 RANDOM FILES 


B.3.2.1 Creating А 
Random File 


50 IF ЕОЕ(1) THEN 90 

60 LINE INPUT#1,A$ 

70 PRINT#2,A$ 

80 GOTO 50 

90 CLOSE #1 

100 KILL “NAMES” 

110 REM ADD NEW ENTRIES TO FILE 

120 INPUT "NAME";N$ 

130 IF N$=“" THEN 200 ‘CARRIAGE RETURN EXITS INPUT LOOP 
140 LINE INPUT "ADDRESS? ”;А$ 

150 LINE INPUT “BIRTHDAY? ”;B$ 

160 PRINT*2,N$ 

170 PRINT#2,A$ 

180 PRINT*2,B$ 

190 PRINT:GOTO 1280 

200 CLOSE 

205 REM CHANGE FILENAME BACK TO "NAMES" 

210 NAME "COPY" AS "NAMES" 

2000 IF ERR=53 AND ERL-20 THEN OPEN "O",*2,'COPY":RESUME 120 
2010 ON ERROR GOTO О 


——M— —— — —— á— —P— cA —————— —————— 


The error trapping routine in line 2000 traps a "File does not exist" 
error in line 20. If this happens, the statements that copy the file are 
skipped, and "COPY" is created as if it were a new file. 


Creating and accessing random files requires more program steps 
than sequential files, but there are advantages to taking the extra 
trouble. One advantage is that random files require less room on the 
disk, because MS-BASIC stores them in a packed binary format. (A 
sequential file is stored as a series of ASCII characters.) The biggest 
advantage to random files is that data can be accessed randomly, 
i.e., anywhere on the disk — it is not necessary to read through all 
the information, as with sequential files. This is possible because the 
information is stored and accessed in distinct units called records and 
each record is numbered. 


The statements and functions that are used with random files are: 


OPEN FIELD LSET/RSET GET 
PUT CLOSE LOC 

MKI$ CVI 

MKS$ CVS 

MKD$ CVD 


The following program steps are required to create a random file. 


1. OPEN the file for random OPEN "R',*1,FILE",52 
access ("R" mode). This example 
specifies a record length of 32 bytes. 
If the record length is omitted, the 
default is 128 bytes. 
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2. Use the FIELD statement to FIELD #1, 20 AS N$, 
allocate space in the random 4 AS A$, 8 AS P$ 
buffer for the variables that will be 
written to the random file. 


3. Use LSET to move the data LSET N$=X$ 
into the random buffer. ІЗЕТ А%-МК5% AMT) 
Митегіс values must be made LSET P$=TEL$ 


into strings when placed in the buffer. 
То do this, use the “таке” functions: 
MKI$ to make an integer value into а 
string, MKS$ for a single precision 
value, and MKD$ for a double 
precision value. 


4. Write the data from the БиНег РОТ “1 СОрЕ% 
to the disk using the РОТ statement. 


Figure B-4 takes information that is input at the terminal and writes it 
to a random file. Each time the PUT statement is executed, a record 
is written to the file. The two-digit code that is input in line 30 
becomes the record number. 


Figure B-4: Creating a Random File 


10 OPEN “R”,#1,“FILE” 32 

20 FIELD #120 AS N$, 4 AS A$, 8 AS P$ 
30 INPUT “2-DIGIT CODE”;CODE% 
40 INPUT “NAME”-X$ 

50 INPUT “AMOUNT”.AMT 

60 INPUT “PHONE”-TEL$:PRINT 
70 LSET N$-X$ 

80 ISET A$-MEKS$( AMT) 

90 LSET P$-TEL$ 

100 PUT #1,CODE% 

110 GOTO 30 


NOTE: Do not use a FIELDed string variable in an INPUT or LET 
statement. This causes the pointer for that variable to point into string 
space instead of the random file buffer. 


B.3.2.2 Accessing A The following program steps are required to access a random 
Random File file: 
1. OPEN the file in "R" mode. OPEN “R”,#1 “FILE” 32 
2. Use the FIELD statement to FIELD #1 20 AS N$, 
allocate space in the random 4 AS A$,8 AS P$ 


buffer for the variables that will be 
read from the file. 


NOTE: In a program that performs 
both input and output on the same 
random file, you can often use just 
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one OPEN statement and one FIELD 


statement. 

3. Use the GET statement to move GET #1 CODE% 
the desired record into the random 
buffer. 

4. The data in the buffer may PRINT N$ 


now be accessed by the program. PRINT CVS(A$) 
Numeric values must be converted 

back to numbers using the "convert" 

functions: CVI for integers, CVS for 

single precision values, and CVD for 

double precision values. 


The program in Figure B-5 accesses the random file "FILE" that was 
created in Figure B-4. By inputting the three-digit code at the terminal, 
the information associated with that code is read from the file and 
displayed. 


Figure B-5: Accessing a Random File 


10 OPEN “R”,#1 FILE” 32 

20 FIELD #1, 20 AS N$, 4 AS А%,8 AS PŠ 
50 INPUT “2-DIGIT CODE”;CODE% 

40 GET #1, CODE% 

50 PRINT N$ 

60 PRINT USING “$$###.##";CVS(AS) 

70 PRINT P$:PRINT 

80 GOTO 50 


With random files, the LOC function returns the "current record 
number." The current record number is one plus the last record 
number that was used in a GET or PUT statement. For example, the 
statement: 


IF LOC(1)>50 THEN END 


ends program execution if the current record number in file#1 is 
higher than 50. 


Figure B-6 shows an inventory program that illustrates random file 
access. In this program, the record number is used as the part 
number, and it is assumed the inventory will contain no more than 
100 different part numbers. Lines 900-960 initialize the data file by 
writing CHR$(255) as the first character of each record. This is used 
later (line 270 and line 500) to determine whether an entry already 
exists for that part number. 


Lines 130-220 display the different inventory functions that the 


program performs. When you type in the desired function number, line 
230 branches to the appropriate subroutine. 
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Figure B-6: Example Program Using a Random Access File 


120 ОРЕМ“В”,#1 “INVEN.DAT” Z9 
125 FIELD#1,1 AS F$,50 AS D$, 2 AS Q$2 AS R$4 AS P$ 
150 PRINT:PRINT "FUNCTIONS:".PRINT 
155 PRINT 1,“INITIALIZE FILE" 
140 PRINT 2,CREATE A NEW ENTRY” 
150 PRINT 3,“DISPLAY INVENTORY FOR ONE PART" 
160 PRINT 4,“ADD TO STOCK” 
170 PRINT 5,“SUBTRACT FROM STOCK” 
180 PRINT 6,“DISPLAY ALL ITEMS BELOW REORDER LEVEL” 
220 PRINT:PRINT:INPUT“FUNCTION”:FUNCTION 
885 IF (FUNCTION<1)OR(FUNCTION>6) THEN PRINT 
“BAD FUNCTION NUMBER”:GO TO 130 
230 ON FUNCTION GOSUB 900,250,390,480,560,680 
240 GOTO 220 
250 REM BUILD NEW ENTRY 
260 GOSUB 840 
270 IF ASC(F$)>255 THEN INPUT"OVERWRITE'.A$: 
IF А$>“У” THEN RETURN 
280 LSET F$-CHR$(O) 
290 INPUT "DESCRIPTION";DESC$ 
300 ІЗЕТ D$-DESC$ 
310 INPUT "QUANTITY IN STOCK";Q96 
320 LSET 0%-МК1%(0%) 
330 INPUT “REORDER LEVEL";R96 
340 LSET R$=MKI$(R%) 
350 INPUT "UNIT PRICE";P 
360 LSET P$=MKS$(P) 
570 PUT#1,PART% 
380 RETURN WE 
390 REM DISPLAY ENTRY 
400 GOSUB 840 
410 IF ASC(F$)=255 THEN PRINT "NULL ENTRY':RETURN 
420 PRINT USING "PART NUMBER ###”.PART% 
450 PRINT D$ 
440 PRINT USING "QUANTITY ON HAND #####”.CV1(Q$) 
450 PRINT USING “REORDER LEVEL #####”.CVI(R$) 
460 PRINT USING "UNIT PRICE $$4* s". CVS( P$) 
470 RETURN 
480 REM ADD TO STOCK 
490 GOSUB 840 
500 IF ASC(F$)=255 THEN PRINT "NULL ENTRY":RETURN 
510 PRINT D$:INPUT "QUANTITY TO ADD" ;A% 
520 0%-СУ1(0%)-А% 
580 ІБЕТ 0%-МК1%(0%) 
540 РОТ#1РАВТ% 
550 ВЕТОВМ 
560 REM REMOVE FROM STOCK 
570 GOSUB 840 
580 IF ASC(F$)=255 THEN PRINT "NULL ENTRY":RETURN 
590 PRINT D$ 
600 INPUT “QUANTITY TO SUBTRACT”:8% _ 
610 Q%=CVI(Q$) | 
620 ІР (Q%-8%)<O THEN PRINT “ONLY”;Q%; “IN STOCK":GOTO 600.7 
650 Q%=Q%-S% 
640 IF Q%=<CVI(R$) THEN PRINT “QUANTITY NOW”;Q%; 
“ REORDER LEVEL';CVI( R$) 


650 
660 
670 
680 
690 
710 
720 


750 
740 
840 
850 


890 
900 
910 
920 
930 
940 
950 
960 


ІЗЕТ 0%-МК1%(0%) 

PUT#1 PART% 

RETURN 

DISPLAY ITEMS BELOW REORDER LEVEL 

КОВ, І-1 TO 100 

GET#1 І 

IF CVI(Q$)CVI(R$) THEN PRINT 0%; QUANTITY”; 
CVI(Q$) ТАВ(50) “REORDER LEVEL”;CVI(R$) 

NEXT I 

RETURN 

INPUT “PART NUMBER”;PART% 

IF(PART%<1)OR(PART%>100) THEN PRINT “BAD PART 

NUMBER”: GOTO 840 ELSE GET#1,PART%:RETURN 

END | 

REM INITIALIZE FILE 

INPUT “ARE YOU ЗОВЕ”.В$:ТЕ B$- "Y" THEN RETURN 

LSET F$=CHR$(258) 

FOR I-1 TO 100 

PUT#1 I 

NEXT I 

RETURN 
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APPENDIX C: Using MS-BASIC with the CP/M-86 Operating 
System 


The CP/M-86 version of MS-BASIC is supplied on a standard 5% 
inch diskette. The name of the file is MSBASIC.COM for MS-DOS 
or MSBASIC.CMD for CP/M-86. 


To run MSBASIC.CMD, bring up CP/M-86 and type the following: 
A>MSBASIC<RET> 
The system will reply: 


MS-BASIC Version 5.xx 
[ CP/M-86 Version] 
Copyright 1977-1982 (C) by Microsoft 
Created: dd-mmm-yy 
ххххх Bytes free 
Ok 


The initialization dialog has been replaced by a set of options which 
are placed after the MS-BASIC command to CP/M-86. The format of 
the command line is (the command line may appear differently on 
your screen than on this page) 


A>MSBASIC[<filename >] [/F:<number of files >] 
[/M:«highest memory location >] 
[/S:«maximum record size >] 


If <filename> is present, MS-BASIC proceeds as if a RUN 
<filename> command were typed after initialization is complete. A 
default extension of .BAS is used if none is supplied and the filename 
is less than 9 characters long. This allows MS-BASIC programs to be 
executed in batch mode using the SUBMIT facility of CP/M-86. Such 
programs should include a SYSTEM statement (see below) to return 
to CP/M-86 when they have finished, allowing the next program in 
the batch stream to execute. 


If /F:<number of files» is present, it sets the number of disk data 
files that may be open at any one time during the execution of a 
MS-BASIC program. Each file data block allocated in this fashion 
requires 166 bytes of memory. If the /F option is omitted, the number 
of files defaults to 3. 


The /M:<highest memory location? option sets the highest memory 
location that will be used by MS-BASIC. In some cases it is desirable 
to set the amount of memory well below the CP/M-86's FDOS to 


МЛ 


С.2 DISK FILES 


АНЕ UEM S RZENUOENIS 
C.3 FILES COMMAND 


reserve space for assembly language subroutines. In all cases, 
«highest memory location?» should be below the start of FDOS 
(whose address is contained in locations 6 and 7). If the /M option is 
omitted, all memory up to the start of FDOS is used. 


/S:<maximum record size? may be added at the end of the 
command line to set the maximum record size for use with random 
files. The default record size is 128 bytes. 


NOTE: «number of files», «highest memory location, and 
«maximum record size» are numbers that may be either decimal, 
octal (preceded by &O) or hexadecimal (preceded by &H). 


Examples: 


А> MSBASIC PAYROLL.BAS Use all memory and 3 files, load 
and execute PAYROLL.BAS. 


А> MSBASIC INVENT/F:6 Use all memory and 6 files, load 
and execute INVENT.BAS. 


A>MSBASIC /М:52768 Use first 32K of memory and 3 files. 


A>MSBASIC DATACK/F:2/M:G'H9000 
Use first 36K of memory, 2 files, and 
execute DATACK.BAS. 


Disk filenames follow the normal CP/M-86 naming conventions. All 
filenames may include A: or B: as the first two characters to specify a 
disk drive, otherwise the currently selected drive is assumed. A 
default extension of .BAS is used on LOAD, SAVE, MERGE and RUN 
«filename» commands if no "." appears in the filename and the 
filename is less than 9 characters long. 


Large random files are supported. The maximum logical record 
number is 32767. If a record size of 256 is specified, then files up to 
8 megabytes can be accessed. 


Format 

FILES[<filename>] 

Purpose: 

Prints the names of files residing on the current disk. 

Remarks: 

If <filename> is omitted, all the files on the currently selected drive 
will be listed. «filename» is a string formula which may contain 
question marks (?) to match any character in the filename or 


extension. An asterisk (*) as the first character of the filename or 
extension will match any file or any extension. 
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Examples: 
FILES 
FILES “* BAS” 


FILES “B:*.*” 
FILES “TEST? BAS” 


Format: 
RESET 
Purpose: 


Closes all disk files and writes the directory information to a diskette 
before it is removed from a disk drive. 


Remarks: 

Always execute a RESET command before removing a diskette from 
a disk drive. Otherwise, when the diskette is used again, it will not 
have the current directory information written on the directory track. 


RESET closes all open files on all drives and writes the directory 
track to every diskette with open files. 


Format: 

LOF(<file number>) 

Action: 

Returns the number of records present in the last extent read or 
written. If the file does not exceed one extent (128 records), then LOF 
returns the true length of the file. 


Example: 


110 IF NUM%>LOF(1) THEN PRINT “INVALID ENTRY” 


With CP/M-86, the EOF function may be used with random files. If a 
GET is done past the end of file, EOF will return -1. This may be 
used to find the size of a file using a binary search or other algorithm. 


1. CSAVE and CLOAD are not implemented. 

2. To return to CP/M-86, use the SYSTEM command or statement. 
SYSTEM closes all files and then performs a CP/M-86 warm start. 
Alt-C always returns to MS-BASIC, not to CP/M-86. 


3. FRCINT is at 103 hex and MAKINT is at 107 hex. 


ees 
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APPENDIX D: Using MS-BASIC with the MS-DOS Operating 
System 


The MS-DOS version of MS-BASIC is supplied on a standard 5% 
inch diskette. The name of the file is MSBASIC.COM. (A 48K or 
larger MS-DOS system is recommended.) 


To run MS-BASIC, bring up MS-DOS and type: 
A>MSBASIC<RET> 
The system will reply: 


MS-BASIC Rev. 5.xx 
[86-DOS Version] 
Copyright 1977-1981 (C) by Microsoft 
Created: dd-mmm-yy 
xxxxx Bytes free 
Ok 


The initialization dialog has been replaced by a set of options which 
are placed after the MS-BASIC command te MSDOS. The format of the 
command line is (the command line may appear somewhat differently 
on your screen than on this page): 


A>MSBASIC [<filename>][/F:<number of files] 
[/M:<highest memory location>][/S:<maximum record 
size>] 


If <filename> is present, MS-BASIC proceeds as if a RUN 
<filename> command were typed after initialization is complete. A 
default extension of .BAS is used if none is supplied and the filename 
is less than 9 characters long. This allows MS-BASIC programs to be 
executed in batch mode using the SUBMIT facility of MS-DOS. Such 
programs should include a SYSTEM statement (see below) to return 
to MS-DOS when they have finished. This allows the next program in 
the batch stream to execute. 


If /F:<number of files is present, it sets the number of disk data 
files that may be open at any one time during the execution of a 
MS-BASIC program. Each file data block allocated in this fashion 
requires 166 bytes of memory. If the /F option is omitted, the number 
of files defaults to 3. 


The /M:<highest memory location? option sets the highest memory 
location that will be used by MS-BASIC. 
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25:<тахітит record size may be added at the end of the 
command line to set the maximum record size for use with random 
files. The default record size is 128 bytes. 


NOTE: <number of files>, <highest memory location>, and 
<maximum record size> are numbers that may be either decimal, 
octal (preceded by &O) or hexadecimal (preceded by &H). 


Examples: 


A>MSBASIC PAYROLL.BAS Use all memory and 3 files, load 
and execute PAYROLL.BAS. 


A>MSBASICINVENT/F6 Use all memory and 6 files, load 
and execute INVENT.BAS. 


A>MSBASIC /M:32768 Use first 32K of memory and 3 files. 


A>MSBASIC DATACK/F:2/M:H9000 
Use first 36K of memory, 2 files, 
and execute DATACK.BAS. 


Disk file names follow the normal MS-DOS naming conventions. All 
file names may include A: ог В: as the first two characters (to specify 
a disk drive); otherwise the currently selected drive is assumed. A 
default extension of .BAS is used оп LOAD, SAVE, MERGE and RUN 
<filename> commands if no "." appears in the file name and the file 
name is less than 9 characters long. 


Large random files are supported. The maximum logical record 
number is 32767. If a record size of 256 is specified, then files ир to 
8 megabytes can be accessed. 


Format: 

FILES[<filename>] 

Purpose: 

Prints the names of files residing on the current disk. 
Remarks: 


If <filename> is omitted, all the files on the currently selected drive 
will be listed. «filename» is a string formula which may contain 
question marks (?) to match any character in the file name or 
extension. Asterisk (*) as the first character of the file name or 
extension will match any file or any extension. 


Examples: 


FILES 

FILES “*:*.*” 

FILES “B:*.*” 
FILES "TEST?.BAS" 


D.4 RESET Format: 
COMMAND 
RESET 
Purpose: 


Closes all disk files and writes the directory information to a diskette 
before it is removed from a disk drive. 


Remarks: 

Always execute a RESET command before removing a diskette from 
a disk drive. If you forget, the diskette will not have the current 
directory information written on the directory track when it is used 
again. 


EE 
D.5 LOF FUNCTION Format: 


LOF(<file number>) 

Purpose: 

Returns the length of the file in bytes. 
Example: 


110 IF NUM%>LOF(1) THEN PRINT “INVALID ENTRY” 


D.6 EOF Format: 
EOF («flle number>) 
Purpose: 


Returns -1 if the end of a sequential or random file has been 
reached. If a GET is done past the end of the file, EOF will return -1. 
EOF may be used to find the size of a file using a binary search or 
other algorithm. 


Example: 


10 OPEN "I",1, "DATA" 
20 С=О 

80 IF EOF(1) THEN 100 
40 INPUT #1,M(C) 

50 C=C+1:GOTO 30 


Se s 
D.7 1. CSAVE and CLOAD are not implemented. 
MISCELLANEOUS 
2. Use the SYSTEM command or statement to return to MS-DOS. 
SYSTEM closes all files and then performs a MS-DOS warm start. 
Alt-C always returns to MS-BASIC, not to MS-DOS. 


3. FRCINT is at 103 hex and MAKINT is at 107 hex. 
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APPENDIX E: Assembly Language Subroutines 


MS-BASIC has provisions for interfacing with assembly language 
subroutines via the USR function and the CALL statement. 


The USR function allows assembly language subroutines to be called 
in the same way MS-BASIC Intrinsic functions are called. 


IMPORTANT: Memory space must be set aside for an assembly 
language subroutine before it can be loaded. During initialization, 
enter the highest memory location minus the amount of memory 
needed for the assembly language subroutine(s) with the /M: switch. 


In addition to the MS-BASIC interpreter code area, MS-BASIC uses up 
to 64K of memory beginning at its data (DS) segment. 


If more stack space is needed when an assembly language 
subroutine is called, the MS-BASIC stack can be saved and a new 
stack set up for use by the assembly language subroutine. The stack 
must be restored, however, before returning from the subroutine. 


You can load the assembly language subroutine into memory by 
using the operating system or the MS-BASIC POKE statement. If 
you have the Programmer's Tool Kit, Volume II, the routines сап be 
assembled with the MACRO-86 assembler and linked using the 
MS-LINK linker, but not assembled. To load the program file, 
observe these guidelines: 


1) The subroutines must not contain any long references. 


2) Skip over the first 512 bytes of the MS-LINK output file, then read 
in the rest of the file. 


The CALL statement is the recommended way of interfacing 8086 
machine language programs with MS-BASIC. It is further suggested 
that the old style user call (x=USR(n)) not be used. 

Format: 

CALL <varlable name> [(<argument list>)] 


where: variable name contains the address that is the starting 
point in memory of the subroutine being CALLed. 


— 


argument list contains the variables or constants, 
separated by соттаз, that are to be passed to the 
routine. 


The CALL statement conforms to the INTEL PL/M-86 calling 
conventions outlined in Chapter 9 of the INTEL PL/M-86 Compiler 
Operator's Manual. MS-BASIC follows the rules described for the 
MEDIUM case (summarized in the following discussion). 


Invoking the CALL statement causes the following to occur: 


1. For each parameter in the argument list, the 2 byte offset of the 
parameter's location within the Data Segment [DS] is pushed onto 
the stack. 


2. MS-BASIC return address Code segment [CS], and offset [IP] are 
pushed onto the Stack. 


3. Control is transferred to the user's routine via an 8086 long call to 
the segment address given in the last DEF SEG statement, and 
offset given іп <variable name>. 


These actions are illustrated by the two following diagrams, which 
illustrate, first, the state of the stack at the time of the CALL 
statement, and, second, the condition of the stack during execution of 
the CALLed subroutine. 


Figure E-1: Stack Layout when CALL Statement is Activated 


high 
addresses parameter 0 
parameter 1 
Each parameter is a 2 
byte POINTER into memory 


C 
S o parameter n 
t u 
a n 
С t return segment address 
k e 
r return offset 
Stack pointer (SP reg. contents) 
V 
low 
addresses 
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The user's routine now has control. Parameters may be referenced by 
moving the Stack pointer [SP] to the Base Pointer [BP] and adding a 
positive offset to [BP]. 
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Figure E-2: Stack Layout During Execution of a CALL Statement 
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You must observe the following rules when coding a subroutine: 


1. The CALLed routine may destroy the AX, BX, CX, DX, SI, DI, and 
BP registers. 


2. The CALLed program MUST know the number and length of the 
parameters passed. References to parameters are positive offsets 
added to [BP] (assuming the called routine moved the current 
Stack pointer into BP; i.e. MOV BP,SP). That is, the location of p1 
is at 8[BP], p2 is at 6[BP], рз is at 4[BP], . . . etc. 


3. The CALLed routine must do a RET «n» (where «n» is two 
times the number of parameters in the argument list) to adjust the 
stack to the start of the calling sequence. 


4. Values are returned to MS-BASIC by including in the argument list 
the variable name which will receive the result. 


9. If the argument is a string, the parameter's offset points to 3 bytes — 
called the "String Descriptor." Byte 0 of the string descriptor | 
contains the length of the string (0 to 255). Bytes 1 and 2, 
respectively, are the lower and upper 8 bits of the string starting 
address in string space. 
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IMPORTANT: If the argument is a string literal in the program, the 
string descriptor will point to program text. Be careful not to alter 
or destroy your program this way. To avoid unpredictable results, 
add +”” to the string literal in the program. Example: 


% n 90 A$ = “BASIC +“ ” 


This will force the string literal to бе copied into string space. Now 
the string may be modified without affecting the program. 


6. Strings may be altered by user routines, but the length MUST 
NOT be changed. MS-BASIC cannot correctly manipulate strings if 
their lengths are modified by external routines. 


Example: 


100 DEF SEG=é&H8000 
110 FOO=0 
120 CALL FOO(A,B$,C) 


Line 100 sets the segment to 8000 Hex. The value of FOO is added 
into the address as the low word after the DEF SEG value is left 
shifted 8 bits. Here, FOO is set to zero, so that the call to FOO will 
execute the subroutine at location 80000H. 


The following sequence of 8086 assembly language demonstrates 
access of the parameters passed and storing a return result in the 


variable 'C'. 

Example: 
МОУ BP SP ; Get current Stack posn in BP. 
MOV BX 6[BP] ; Get address of B$ dope. 
МОУ  CL[BX] ; Get length of B$ in CL. 
МОУ DX,1[BX] ‚ Get address of B$ text in DX. 
MOV 818[ВР] ‚ Get address of ‘A’ in SI. 
MOV DIA[BP] ; Get pointer to 'C' in DI. 
MOVS WORD : Store variable ‘A’ іп “С. 
RET 6 ; Restore Stack, return. 


IMPORTANT: The called program must know the variable type for 
numeric parameters passed. In the above example, the instruction 
MOVS WORD will copy only 2 bytes. This is fine if variables A and C 
are integer. We would have to copy 4 bytes if they were Single 
Precision and copy 8 bytes if they were Double Precision. 
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E.3 USING USR The format of the УЗВ function call is: 
FUNCTION CALLS 

x = USR[<digit>](argument) 


where: <digif> is from 0 to 9. <digif> specifies which USR 
routine is being called. (See “The DEF USR Statement''). 
If «digit is omitted, USRO is assumed. 


argument is any numeric or string expression. 


x is the variable receiving the result of the function call. 
Its type (numeric or string) must be consistent with the 
argument passed, or may be set to Integer by calling 
MAKINT in the user's routine before returning to 
MS-BASIC. 


A DEF SEG statement MUST be executed prior to a USR call to 
assure that the Code Segment points to the subroutine being called. 
The segment given in the DEF SEG statement determines the starting 
segment of the subroutine. (See the DEF SEG statement above.) 


For each USR function used, a corresponding DEF USR statement 
must have been executed to define the USR call offset. The address 
given in the DEF USR statement determines the starting address of 
the subroutine. 


When the USR function call is made, register [AL] contains a value 
that specifies the type of argument that was given. The value in [AL] 
may be one of the following: 


2 Two-byte integer (two's complement) 
3 String 

4 Single precision floating point number 
8 Double precision floating point number 


Н the argument is a number, the [BX] register pair points to the 
Floating Point Accumulator (FAC) where the argument is stored. 


FAC is the exponent minus 128, and the binary point 
is to the left of the most significant bit of the 
mantissa. 


FAC-1 contains the highest 7 bits of mantissa with leading 1 


suppressed (implied). Bit 7 is the sign of the number 
(O=positive, 1 =negative). 


Н the argument is an integer: P 


FAC-2 contains the upper 8 bits of the argument. 


FAC-3 contains the lower 8 bits of the argument. 
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Example: 


Example: 


if the argument is a single precision floating point number: 
FAC-2 contains the middle 8 bits of mantissa. 
FAC-3 contains the lowest 8 bits of mantissa. 
If the argument is a double precision floating point number: 


FAC-7 contain four more bytes of mantissa (FAC-7 
To contains the lowest 8 bits). 
FAC-4 


If the argument is a string, the [DX] register pair points to 3 bytes 
called the “string descriptor.” Byte 0 of the string descriptor contains 
the length of the string (0 to 255). Bytes 1 and 2, respectively, are the 
lower and upper 8 bits of the string starting address іп MS-BASIC's 
Data Segment. 


IMPORTANT: If the argument is a string literal in the program, the 
string descriptor will point to program text. Be careful not to alter or 
destroy your program this way. See the CALL statement above. 


Usually, the value returned by a USR function is the same type 
(integer, string, single precision or double precision) as the argument 
that was passed to it. 


110 DEF USRO=&H8000 ‘Assumes user gave /M:32767 
120 X=5 ‘Note that X is single precision 

180 Y = USRO(X) 

140 PRINT Y 


We have loaded the following assembly language routine to simply 
multiply the argument passed by 2 and return an integer result. 


Always be sure that your programs are defined by a PROC FAR 
statement. 


DOUBLE SEGMENT 

ASSUME  CS:DOUBLE 
FRCINTOFFSET EQU 103H 
MAKINTOFFSET EQU 107H 
FRCINT LABEL DWORD 

DW FRCINTOFFSET 
FRCSEG DW ? 
MAKINT LABEL DWORD 

DW MAKINTOFFSET 
MAKSEG DW Ф 
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USRPRG PROC FAR 


POP SI 
POP AX ; Recover MS-BASIC CS 
PUSH AX 
PUSH SI 
MOV FRCSEG,AX ; Set segment for long indirect CALL 
MOV MAKSEG.AX 
CALL FRCINT ‚ Force arg in FAC to int in [BX] 
ADD BX,BX . [BX] = [ВХ] * 2 
CALL MAKINT . Put Result back in FAC 
RET ‚ Long return to MS-BASIC 
USRPRG ENDP 
DOUBLE ENDS 


When FRCINT or MAKINT is called and when the subroutine 
terminates with a return, ES, DS, and SS must have the same value 


they had when the subroutine was entered. These registers point to 
the MS-BASIC Data Segment. 
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[Ea 
F.1 OPERATIONAL 
DIFFERENCES 


APPENDIX F: MS-BASIC Compiler 


The MS-BASIC Compiler package contains the following soft- 
ware: MS-BASIC Compiler, MACRO assembler, and LINK loader. 
These manuals are also supplied: MS-BASIC Reference Manual, 
MS-BASIC Compiler Programmer's Guide, and Programmer's Tool 
Kit, Volume II. The Programmer's Tool Kit describes the use of 

the MACRO-86 macroassembler and the MS-LINK linker utility. The 
MS-BASIC Compiler Programmer's Guide describes the use 

of the compiler, its command format, compilation switches, 

and error messages. The MS-BASIC language that is used with the 
MS-BASIC Compiler is the same as the MS-BASIC described in 
this manual, with the following exceptions. 


The Compiler interacts with the console only to read compiler 
commands. These specify what files are to be compiled. There is no 
"direct mode," as with the MS-BASIC interpreter. Commands that are 
usually issued in the direct mode with the MS-BASIC interpreter are 
not implemented on the compiler. 


The following statements and commands are not implemented and 
will generate an error message: 


AUTO CONT DELETE 
EDIT ERASE LIST 
LOAD MERGE NEW 
RENUM LLIST SAVE 


Because there is no direct mode for typing in programs or edit mode 
for editing programs, use the MS-BASIC interpreter for creating and 
editing programs. If you use the interpreter, be sure to SAVE the file 
with the A (ASCII format) option. 


The compiler cannot accept a physical line that is more than 253 
characters in length. A logical statement, however, may contain as 
many physical lines as desired. Use line feed to start a new physica! 
line within a logical statement. 


To reduce the size of the compiled program, there are no program 
line numbers included in the object code generated by the compiler 
unless the /D, /X, or /E switch is set in the compiler command. As a 
result, error messages contain the address where the error occurred, 
instead of a line number. The compiler listing and the map generated 
by LINK are used to identify the line that has the error. It is always a 
good idea to debug programs using the MS-BASIC Interpreter 
before attempting to compile them. See the MS-BASIC Compiler 
Programmer's Guide for more information. 
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F.2 LANGUAGE Most programs that run on the MS-BASIC interpreter will run on the 

DIFFERENCES MS-BASIC compiler with little or no change. However, it is necessary 
to note differences in the use of the following program statements: 


1. CALL 


The <variable-name> field in the CALL statement must contain an 
external symbol, і.е., one that is recognized by LINK as a global 
symbol. This routine must be supplied by the user as an assembly 
language subroutine or a routine from the FORTRAN library. 


2. CHAIN and RUN 


The CHAIN statement is used to chain to a new program overlay 
using the runtime module. The RUN statement is to be used to 
execute any executable file. (Refer to Appendix C for СР/М and 
Appendix D for MS-DOS). 


3. CLEAR 


The CLEAR statement is only supported in compiled programs 
using the runtime module. 


4. COMMON 


The COMMON statement must appear before any executable 
statements. See section 2.7 for further details. 


5. DEFINT/SNG/DBL/STR 


The compiler does not "execute" DEFxxx statements; it reacts to 
the static occurrence of these statements, regardless of the order 
in which program lines are executed. A DEFxxx statement takes 
effect as soon as its line is encountered. Once the type has been 
defined for a given variable, it remains in effect until the end of 
the program or until a different DEFxxx statement with that 
variable takes effect. 


6. DIM and ERASE 


The DIM statement is similar to the DEFxxx statement in that it is 
scanned rather than executed. That is, DIM takes effect when its 
line is encountered. If the default dimension (10) has already been 
established for an array variable and that variable is later 
encountered in a DIM statement, a "Redimensioned array" error 
results. 


There is no ERASE statement in the compiler, so arrays cannot 
be erased and redimensioned. An ERASE statement will produce 
a fatal error. 


Also note that the values of the subscripts in a DIM statement Nus 
must be integer constants; they may not be variables, arithmetic 
expressions, or floating point values. 
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Example: 


DIM A1 (Т) 
DIM А1 (5-4) 


. „/ are both illegal. 


7. END 


During execution of a compiled program, an END statement 
closes files and returns control to the operating system. The 
compiler assumes an END statement at the end of the program, 
so “running off the end” produces proper program termination. 


8. FOR/NEXT and WHILE/WEND 
Loops must be statically nested when using these statements. 
9. ON ERROR GOTO/RESUME «/ine number» 


If a program contains ON ERROR СОТО and RESUME «Jine 
number? statements, the /E compilation switch must be used. If 
the RESUME NEXT, RESUME, or RESUME 0 form is used, the /X 
switch must also be included. See the М5-ВА5/С Compiler 
Programmer's Guide for an explanation of these switches. 


10. REM 


REM statements or remarks starting with a single quotation mark 
do not take up time or space during execution, and so may be 
used as freely as desired. 


11. STOP 


The STOP statement is identical to the END statement. Open 
files are closed and control returns to the operating system. 


12. TRON/TROFF 


In order to use TRON/TROFF, the /D compilation switch must be 
used. Otherwise, TRON and TROFF are ignored and a warning 
message is generated. 


13. USRn Functions 


USRn Functions are significantly different from the interpreter 
versions. The argument to the USRn function is ignored and an 
integer result is returned in the HL registers. It is recommended 
that USRn functions be replaced by the CALL statement. 


14. %INCLUDE 
Na The %INCLUDE «filename? statement allows the compiler to 


include source from an alternate file. The %INCLUDE statement 
must be the last statement statement on a line. The format of the 
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222222542225) 
F.3 EXPRESSION 


EVALUATION 
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Example: 


%INCLUDE statement is: 
«line number> %INCLUDE «filename» 
Example: 
999 %INCLUDE SUB1000.BAS 
15. Double-Precision Transcendental Functions 


SIN, COS, TAN, SQR, LOG, and EXP return double precision 
results if given a double precision argument. Exponentiation 

with double precision operands will return a double precision 
result. 


16. String Variables 


The string space is maintained differently with the MS-BASIC 
Compiler than with the interpreter. Using PEEK, POKE, 
VARPTR, or assembly language routines to change string 
descriptors will result in a “String Space Corrupt” error. 


During expression evaluation, the operands of each operator are 
converted to the same type, that of the most precise operand. 


Example: 
QR=J%+A. !+Q# 


causes J% to be converted to single precision and added to A !. this 
result is converted to double precision and added to Он. 


The compiler is more limited than the interpreter in handling numeric 
overflow. For example, when run on the interpreter the following 
program: 


АЕ LC К PEN эше =: 


1%=20000 

<%-20000 

K%=30000 

M%=I1%+I%-K% 
TE u i = 


ylelds 10000 for M%. That is, it adds 1% to J% and, because the 
number is too large, it converts the result into a floating point number. 
K% is then converted to floating point and subtracted. The result of 
10000 is found, and is converted back to integer and saved as M%. 


The compiler, however, must make type conversion decisions during 
compilation. It cannot defer until the actual values are known. Thus, 

the compiler would generate code to perform the entire operation in 

integer mode. If the /D switch were set, the error would be detected. 
Otherwise, an incorrect answer would be produced. 


F.4 INTEGER 
VARIABLES 


Example: 


Example: 


In order to produce optimum efficiency in the compiled program, the 
compiler may perform any number of valid algebraic transformations 
before generating the code. For example, the program. 


Бы sisa Eua 


1%-20000 
J%=18000 
K%=20000 
M%=I%+JI%+tK% 


—— u Trwarrrraarrr curar mr 


could produce an incorrect result when run. If the compiler 
actually performs the arithmetic in the order shown, по 
overflow occurs. However, if the compiler performs %+К% first 
and then adds J%, an overflow will occur. The compiler follows 
the rules for operator precedence and parenthetic modification 
of such precedence, but no other guarantee of evaluation order 
can be made. 


In order to produce the fastest and most compact object code 
possible, make maximum use of integer variables. For example, this 
program: 


FOR 1=1 ТО 10 
А (1)=0 
NEXT I 
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can execute approximately 30 times faster by simply substituting "1%" 
for “1”. It is especially advantageous to use integer variables to 
compute array subscripts. The generated code is significantly faster 
and more compact. 
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APPENDIX G: Summary of Error Codes and Error Messages 


CODE NUMBER MESSAGE 


NF 1 NEXT without FOR 
A variable in a NEXT statement does not 
correspond to any previously executed, unmatched 
FOR statement variable. 


SN 2 Syntax error 
A line is encountered that contains some incorrect 
sequence of characters (such as unmatched 
parentheses, misspelled command or statement, 
incorrect punctuation, etc.). 


RG 3 Return without GOSUB 
A RETURN statement is encountered for which 
there is no previous, unmatched GOSUB statement. 


OD 4 Out of DATA 
A READ statement is executed when there are no 
DATA statements with unread data remaining in 
the program. 


FC 5 Illegal function call 
A parameter that is out of range is passed to a 
math or string function. An FC error may also 
occur as the result of 
1. А negative or unreasonably large subscript 
2. А negative or zero argument with LOG 
3. А negative argument to SQR 


4. А negative mantissa with а non-integer 
exponent 


5. А call to a USR function for which the starting 
address has not yet been given 


6. An improper argument to MID$, LEFT$, 
RIGHTS, INP, OUT, WAIT, PEEK, POKE, TAB, 
SPC, STRINGS, SPACES. INSTR, or ОМ... GOTO. 
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OV 6 Overflow 
The result of a calculation is too large to be 
represented in MS-BASIC number format. If 
underflow occurs, the result is zero and execution 
continues without an error. 


OM 7 Оч of memory 
A program is too large, has too many FOR loops 
or GOSUBs, too many variables, or expressions 
that are too complicated. 


UL 8 Undefined line number 
A line reference in а GOTO, GOSUB, IF ... THEN 
.., ELSE or DELETE is to a nonexistent line. 


BS 9 Subscript out of range 
An array element is referenced either with a 
subscript that is outside the dimensions of the 
array, or with the wrong number of subscripts. 


DD 10 Duplicate definition 
Two DIM statements are given for the same array, 
or a DIM statement is given for an array after the 
default dimension of 10 has been established for 
that array. 


/0 11 Division by zero 

A division by zero is encountered in an expression, 
“ә or the operation of involution results іп zero being 

raised to a negative power. Machine infinity with 

the sign of the numerator is supplied as the result 

of the division, or positive machine infinity is 

supplied as the result of the involution, and 

execution continues. 


ID 12 Illegal direct 
A statement that is illegal in direct mode is 
entered as a direct mode command. 


TM 13 Type mismatch 
A string variable name is assigned a numeric 
value or vice versa; a function that expects а 
numeric argument is given a string argument or 
vice versa. 


OS 14 Out of string space 
String variables have caused MS-BASIC to exceed 
the amount of free memory remaining. MS-BASIC 
will allocate string space dynamically, until it runs 
out of memory. 


String too long 
An attempt is made to create a string more than 
255 characters long. 
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ST 


CN 


UF 


18 


19 


20 


21 


22 


23 


26 


29 


30 


DISK 
50 


String formula too complex 

A string expression is too long or too complex. 
The expression should be broken into smaller 
expressions. 


Can't continue 
An attempt is made to continue a program that. 


1. Has halted due to an error. 


2. Has been modified during a break in execution. 


3. Does not exist. 


Undefined user function 
A USR function is called before the tunction 
definition (DEF statement) is given. 


No RESUME 
An error trapping routine is entered but contains 
no RESUME statement. 


RESUME without error 
A RESUME statement is encountered before an 
error trapping routine is entered. 


Unprintable error 

An error message is not available for the error 
condition which exists. This is usually caused by 
an ERROR with an undefined error code. 


Missing operand 
An expression contains an operator with no 
operand following it. 


Line buffer overflow 
An attempt is made to input a line that has too 
many characters. 


FOR without NEXT 
A FOR was encountered without a matching NEXT. 


WHILE without WEND 
A WHILE statement does not have a matching 
WEND. 


WEND without WHILE 
A WEND was encountered without a matching 
WHILE. 


ERRORS 


Field overflow 
A FIELD statement is attempting to allocate more 
bytes than were specified for the record length of 
a random file. 


SS 
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52 


53 


54 


55 


57 


58 


61 


62 


63 


64 
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Internal error 

An internal malfunction has occurred in 
MS-BASIC. Report the conditions under which 
the message appeared to your dealer. 


Bad file number 
A statement or command references a file with a 
file number that is not OPEN or is out of the range 


. of file numbers specified at initialization. 


File not found 
A LOAD, KILL or OPEN statement references a 
file that does not exist on the current disk. 


Bad file mode 

An attempt is made to use PUT, GET, or LOF with 
a sequential file, to LOAD a random file or to 
execute an OPEN with a file mode other than |, О, 
or R. 


File already open 

A sequential output mode OPEN is issued for a file 
that is already open; or a KILL is given for a file 
that is open. 


Disk I/O error 

An I/O error occurred on a disk I/O operation. It 
is a fatal error, i.e., the operating system cannot 
recover from the error. 


File already exists 
The filename specified in a NAME statement is 
identical to a filename already in use on the disk. 


Disk full 
All disk storage space is in use. 


Input past end 

An INPUT statement is exeucted after all the data 
in the file has been INPUT, or for a null (empty) 
file. To avoid this error, use the EOF function to 
detect the end of file. 


Bad record number 

In a PUT or GET statement, the record number is 
either greater than the maximum allowed (32767) 
or equal to zero. 


Bad file name 

An illegal form is used for the filename with LOAD, 
SAVE, KILL, or OPEN (e.g., a filename with too 
many characters). 


Direct statement in file 


A direct statement is encountered while LOADing 
an ASCII-format file. The LOAD is terminated. 
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Too many files 

An attempt is made to create a new file (using 
SAVE or OPEN) when all 255 directory entries are 
full. 


APPENDIX H: Mathematical Functions 


Functions that are not intrinsic to MS-BASIC may be calculated as 


follows. 


FUNCTION 


SECANT 
COSECANT 
СОТАМСЕМТ 
INVERSE SINE 
INVERSE COSINE 
INVERSE SECANT 


INVERSE COSECANT 


INVERSE COTANGENT 
HYPERBOLIC SINE 
HYPERBOLIC COSINE 


HYPERBOLIC TANGENT 


HYPERBOLIC SECANT 


HYPERBOLIC 
COSECANT 


HYPERBOLIC ° 
COTANGENT 


INVERSE HYPERBOLIC 
SINE 


INVERSE HYPERBOLIC 
COSINE 


INVERSE HYPERBOLIC 
TANGENT 


INVERSE HYPERBOLIC 
SECANT 


INVERSE HYPERBOLIC 
COSECANT 


INVERSE HYPERBOLIC 
COTANGENT 


MS-BASIC EQUIVALENT 


SEC(X)-1/COS(X) 

С$С(Х)=1 /SIN(X) 

СОТ(Х)=1 /TAN(X) 
ARCSIN(X)=ATN(X/SQR(-X*X+1 )) 
ARCCOS(X)=-ATN(X/SQR(-X*X+1 ))+1 5708 


ARCSEC(X)=ATN(X/SQR(X*X-1)) 
+SGN(SGN(X)-1 )*1.5708 


ARCCSC(X)=ATN(X/SQR(X*X-1 )) 
+(SGN(X)-1)*1.5708 


ARCCOT(X)=ATN(X)+1 5708 
SINH(X)=(EXP(X)-EXP(-X))/2 
COSH(X)=(EXP(X)+EXP(-X))/2 
ТАМН(Х)=ЕХР(-Х)/ЕХР(Х)+ЕХР(-Х))*2+1 
ЗЕСН(Х)=2 /(ЕХР(Х)+ЕХР(-Х)) 


CSCH(X)22/(EXP(X)-EXP(-X)) 
COTH(X)-EXP( -X)/(EXP(X)-EXP(-X))*2+1 
ARCSINH(X)=LOG(X+SQR(X*X +1 )) 
ARCCOSH(X)=LOG(X+SQR(X*X-1 ) 
ARCTANH(X)=LOG((1 +X)/(1-X))/2 
ARCSECH(X)=LOG((SQR(-X*X+1 )+1 )/X) 
ARCCSCH(X)-LOG((SGN(X)'SQR(X* X41) 


*1)/X 


ARCCOTH(X)=LOG((X+1 )/(X-1))/2 
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APPENDIX І: ASCII Character Codes 


Dec Hex CHR Dec Hex CHR Dec Hex CHR 


000 оон мл 043 2BH + 086 56H V 
001 01H SOH 044 2CH | 087 57H W 
002 02H  STX 045 2DH - 088 58H X 
003 03H ETX 046 2EH | 089 59H Y 
004 04H EOT 047 2FH / 090 5AH 7 
005 05H ЕМО 048 30H O 091 5BH 
006 06H ACK 049 ЗІН 1 092 5CH \ 
007 07H BEL 050 32H 2 093  5DH ] 
08 08H BS 051 33H 3 094 БЕН ^ 
009 09H HT 052 34H 4 095 БЕН  — 
010 OAH LF 053 35H 5 096 60H 

011 OBH VT 054 36H 6 097 61H a 
012 OCH FF 055 37H 7 098 62H b 
оз оон CR 056 38H 8 099 63H C 
014 OEH SO 057 39H 9 100 64H d 
015 OFH 81 058 ЗАН 101 65Н е 
016 10Н DLE 059 3BH : 102 66H f m 
07 11H ОСІ 060 3CH < 103 67H g 
018 12H 062 061 3DH = 104 68H h „г 
019 13H  DC3 062 ЗЕН > 105 69H i 
020 14H  DC4 063 ЗЕН  ? 106 ФАН j 
021 15H NAK 064 40H @ 107 68H k 
022 16H SYN 065 4H A 108 6CH | 
023 17H ETB 066 42H В 109 6DH m 
024 18H CAN 067 43H C 110 6EH n 
025 19H EM 068 44H OD 111 6FH о 
026 ЛАН SUB 069 45Н Е 112 70H р 
027 1ВН ЕЗСАРЕ 070 46Н F 113 71H q 
08 1CH FS 071 47H G 114 72H r 
029 1DH 05 072 48H H 115 73H S 
030 1EH RS 073 49H | 116 74H t 
031 1FH US 074 4AH J 117 75H T 
032 20H SPACE 075 4BH K 118 76H у 
033 21H | 076 4CH L 119 77H w 
034 22H А 077 4DH = M 120 78H x 
035 23H # 078 4EH N 121 79H y 
036 24H $ 079 4FH O 122 ТАН z 
07 25H % 080 5H P 123 7BH | 
038 26H & ой SIH Q 124 7CH | 
039 27H | 082 52H R 125 7DH |} 
040 28H ( 083 53H S 126 7EH ~ ims 
041 29H ) 084 54H T 127 ТЕН DEL 
042 2AH * 085 55H U 


NOTE: Dec=decimal, Hex=hexadecimal (Н), CHR=character, 
LF=Line Feed, FF=Form Feed, CR=Carriage Return, DEL=Rubout. 
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